Package constants by Noremos · Pull Request #8916 · FirebirdSQL/firebird

Noremos · 2026-02-25T08:05:08Z

Package Constants

This PR adds a new database object - Package Constant (#1036). It is a constant value located in a package header (public visibility) or a package body (private visibility). See README.packages.txt for more information.

SYNTAX

Creation:

CREATE PACKAGE <package_name>
AS
BEGIN
    CONSTANT <constant_name> <type> = <constant_expr>; -- public constant
    -- package routines
END

CREATE PACKAGE BODY <package_name>
AS
BEGIN
    CONSTANT <constant_name> <type> = <constant_expr>; -- private constant
    -- package routines
END

<constant_expr> is an expression that remains unchanged after recompilation.

ackage constants can be queried using the expression <package_name>.<consatnt_name> outside the package (<consatnt_name> must be a public constant) and using the expression <consatnt_name> inside the package.
To query a constant, the user/role must have USAGE permission on the package.

Other SQL extensions:

COMMENT ON CONSTANT [<schema>.]<package>.<const_name> IS <text>
GRANT USAGE ON PACKAGE  [<schema>.]<package_name> to [<user|role>] <name> [<grant_option>] [<granted_by>]
REVOKE USAGE ON PACKAGE  [<schema>.]<package_name> FROM <user|role> <name> [<granted_by>]
SHOW CONST[ANTS]  [ [<schema>.]<package_name> ] -- isql only

Usage examples:

set autoterm;
CREATE PACKAGE MY_PACKAGE
AS
BEGIN
    CONSTANT PUBLIC_CONST INTEGER = 10;
    FUNCTION MY_SECRET_PRINT() RETURNS INT;
END;

CREATE PACKAGE BODY MY_PACKAGE
AS
BEGIN
    CONSTANT SECRET_1 INTEGER = 15;
    CONSTANT SECRET_2 INTEGER = 30;

    FUNCTION MY_SECRET_PRINT() RETURNS INT
    AS
    BEGIN
        RETURN SECRET_1 * SECRET_2;
    END
END;
commit;

select MY_PACKAGE.PUBLIC_CONST from rdb$database ;
select MY_PACKAGE.MY_SECRET_PRINT() from rdb$database;

System Constants

As an exmaple, 3 consatnts have been added to the RDB$BLOB_UTIL package

FROM_BEGIN  : INTEGER = 0
FROM_CURRENT : INTEGER = 1
FROM_END : INTEGER = 2

System metadata changes

New system table - RDB$CONSTANTS

Table: SYSTEM.RDB$CONSTANTS
RDB$CONSTANT_NAME               (SYSTEM.RDB$FIELD_NAME) CHAR(63) CHARACTER SET SYSTEM.UTF8 Nullable 
RDB$CONSTANT_ID                 (SYSTEM.RDB$CONSTANT_ID) INTEGER Nullable 
RDB$PACKAGE_NAME                (SYSTEM.RDB$PACKAGE_NAME) CHAR(63) CHARACTER SET SYSTEM.UTF8 Nullable 
RDB$FIELD_SOURCE                (SYSTEM.RDB$FIELD_NAME) CHAR(63) CHARACTER SET SYSTEM.UTF8 Nullable 
RDB$PRIVATE_FLAG                (SYSTEM.RDB$SYSTEM_NULLFLAG) SMALLINT Nullable 
RDB$CONSTANT_BLR                (SYSTEM.RDB$CONSTANT_BLR) BLOB segment 80, subtype BLR Nullable 
RDB$CONSTANT_SOURCE             (SYSTEM.RDB$SOURCE) BLOB segment 80, subtype TEXT CHARACTER SET SYSTEM.UTF8 Nullable 
RDB$SCHEMA_NAME                 (SYSTEM.RDB$SCHEMA_NAME) CHAR(63) CHARACTER SET SYSTEM.UTF8 Nullable 
RDB$DESCRIPTION                 (SYSTEM.RDB$DESCRIPTION) BLOB segment 80, subtype TEXT CHARACTER SET SYSTEM.UTF8 Nullable 
CONSTRAINT RDB$INDEX_98:
  Unique key (RDB$SCHEMA_NAME, RDB$PACKAGE_NAME, RDB$CONSTANT_NAME)
CONSTRAINT RDB$INDEX_99:
  Unique key (RDB$CONSTANT_ID)

A new field has been added to RDB$PACKAGES - RDB$PACKAGE_ID

New indexes:

Unique key SYSTEM.RDB$CONSTANTS  (RDB$SCHEMA_NAME, RDB$PACKAGE_NAME, RDB$CONSTANT_NAME)
Unique key SYSTEM.RDB$CONSTANTS (RDB$CONSTANT_ID)
Unique key SYSTEM.RDB$PACKAGES (RDB$PACKAGE_ID)

Implementation

Packages have been added to the metacaching system. Since it relies heavily on identifiers, a new ID field (RDB$PACKAGE_ID) has been added to the RDB$PACKAGES table. Constants are stored as an array in the package metacaching object, with a package_id-to-array_id and constant_name-to-array_id mappings.

There are also two important points:

All nodes now have an 'is constant' flag, similar to the 'is deterministic' flag. This is necessary to determine whether an expression can initialize a constant.
In the CreateAlterPackageNode node, a lot of code had to be copied and pasted, and adding constants led to complete chaos. Therefore, I decided to slightly refactor this node. All functionality remains the same; only code duplication was removed.

…rong impure cache usage

…stant routine

…_constants

…onstants

sim1984 · 2026-02-25T13:03:32Z

Are comments supported for constants? I didn't see this in the documentation.
Let me clarify what I mean:

COMMENT ON CONSTANT [<schema>.]<package>.<const_name> IS 'Text'

Comments are simply supported for packaged procedures and functions. It would make sense to do the same for constants (and any package objects, for that matter).

COMMENT ON PROCEDURE [<schema>.]<package>.<proc_name> IS 'Text';
COMMENT ON FUNCTION [<schema>.]<package>.<func_name> IS 'Text';

Noremos · 2026-02-25T13:16:08Z

Are comments supported for constants?

No, I didn't plan to implement comments, but I think it's possible. I will take a look

sim1984 · 2026-04-02T08:38:09Z

Aren't system packages created during database creation itself? I.e. even during restore they will be created first, before user packages.

I think the original question was about a situation where there are 4 systemp packages, 1 user packages and a new version adds a new system package. If you preserve the original ID when restoring, the following situation will occur
TimeZonePackage: ID 1
ProfilerPackage: ID 2
BlobUtilPackage: ID 3
SqlPackage: ID 4 
NewSystemPackage: ID 5
UerPackage: ID 5 <- restored package
But the IDs are regenerated, so we are safe.

Yes, that's exactly what I was asking about. Thanks for clarifying.

aafemt · 2026-04-02T08:41:16Z

None of IDs are persistent in Firebird and there is no reason for package's one to be the first.

sim1984 · 2026-04-02T08:44:23Z

None of IDs are persistent in Firebird and there is no reason for package's one to be the first.

This isn't true for relations. That's why I asked.

…onstants

Noremos · 2026-04-02T15:16:02Z

Hmm, I thought that since constants aren't independent objects, it would be enough if the user had permission to create a package. Should I add separate permissions for creating constants?

I'm referring to the outside user of a constant, which should have permission to use the package.

I've added permission checking

connect employee user R;
Database: employee, User: R

SQL> select TEST.C1 from rdb$database;
Statement failed, SQLSTATE = 28000
no permission for USAGE access to PACKAGE "PUBLIC"."TEST"
-Effective user is R

To grant permissions:
grant USAGE on package TEST to user R;
To revoke permissions:
revoke usage on package TEST from user R;

Noremos · 2026-04-02T15:27:05Z

src/burp/backup.epp

+
+	FOR (REQUEST_HANDLE req_handle1)
+		CONST IN RDB$CONSTANTS
+		WITH CONST.RDB$SCHEMA_NAME NE SYSTEM_SCHEMA


Is this check allowed or should I add the RDB$SYSTEM_FLAG field?

…al constants

… grant/revoke for constants in README

Noremos

I think this PR is ready to rereviw @AlexPeshkoff @asfernandes @dyemanov

Noremos · 2026-04-03T09:35:23Z

src/isql/show.epp

+
+		bool isPrivate = !CONST.RDB$PRIVATE_FLAG.NULL && CONST.RDB$PRIVATE_FLAG;
+
+		if (!CONST.RDB$PACKAGE_NAME.NULL)


I removed the checks for now

Noremos · 2026-04-03T09:38:09Z

src/jrd/obj.h

 		case obj_schemas:
 			return "SQL$SCHEMAS";
+		case obj_package_constant:
+			return "SQL$PACKAGE_CONSTANT";


I removed it for now

Noremos · 2026-04-03T09:39:35Z

src/jrd/SysFunction.h

 class SysFunction
 {
 public:
+	enum Flags : UCHAR


I remvoed the NONE

…ilters

…onstants

dyemanov · 2026-04-12T06:20:08Z

doc/sql.extensions/README.packages.txt

        GRANT SELECT ON TABLE secret TO PACKAGE pk_secret;
        GRANT EXECUTE ON PACKAGE pk_secret TO ROLE role_secret;

+      To use package constants in a select expression, a USAGE permission is requeued:


Suggested change

To use package constants in a select expression, a USAGE permission is requeued:

To use package constants in a select expression, a USAGE permission is required:

dyemanov · 2026-04-12T06:21:36Z

doc/sql.extensions/README.packages.txt

+      the [<schema>.]<package>.<constant_name> notation.
+      Constants declared in the package body are private and cannot be accessed from outside the package.
+      However, they can be referenced directly by <constant_name> within <procedure_impl> and <function_impl>.
+      Header constants can also be used directly with just the name for package body elements.


Suggested change

Header constants can also be used directly with just the name for package body elements.

Header constants can also be referenced directly by their name inside package body elements.

dyemanov · 2026-04-12T06:32:13Z

src/dsql/DdlNodes.epp


+		case obj_package_constant:
+			if (!checkObjectExist(tdbb, transaction, objName, objType))
+				status_exception::raise(Arg::PrivateDyn(303) << objName.toQuotedString());	// Package @1 does not exist


Shouldn't it be "Constant does not exist" instead ?

dyemanov · 2026-04-12T06:36:16Z

src/dsql/ExprNodes.cpp

+			if (PackageReferenceNode::constantExists(tdbb, dsqlScratch->getTransaction(), constantName))
+			{
+				packageContext.ctx_relation = nullptr;
+				packageContext.ctx_procedure = nullptr;


These two pointers are already nullified by the dsql_ctx constructor.

dyemanov · 2026-04-12T06:41:44Z

src/dsql/Nodes.h

 		TYPE_WINDOW_CLAUSE,
 		TYPE_WINDOW_CLAUSE_FRAME,
 		TYPE_WINDOW_CLAUSE_FRAME_EXTENT,
+		TYPE_REFERENCE,


Maybe TYPE_PACKAGE_REFERENCE? Just for clarity.

dyemanov · 2026-04-12T06:58:38Z

src/jrd/fields.h

+	FIELD(fld_pkg_id		, nam_pkg_id		, dtype_long	, sizeof(SLONG)				, 0							, NULL		, true		, ODS_14_0)
+
+	FIELD(fld_const_name	, nam_const_name	, dtype_varying	, MAX_SQL_IDENTIFIER_LEN	, dsc_text_type_metadata	, NULL		, false		, ODS_14_0)
+	FIELD(fld_const_id		, nam_const_id		, dtype_long	, sizeof(SLONG)				, 0							, NULL		, true		, ODS_14_0)


The same question as above. Since constants are always packaged and packages now have their own IDs, why would we need IDs for constants?

Can package have more than one constant inside? In absence of ID, constants can be identified only by name which is not always convenient.

I don't mind IDs per se, but there should be some rationale for them.

If constants are expanded beyond packages, perhaps they will have to be presented in lock manager with their ID.

True, but it has already been discussed and the answer was we don't need global constants.

dyemanov · 2026-04-12T07:01:26Z

src/jrd/Package.h

+/*
+ *	PROGRAM:		Firebird CONSTANTS implementation.
+ *	MODULE:			Package.h
+ *	DESCRIPTION:	Routine to cache and reload Package constants


This module is expected to encapsulate other packaged items, so please make the description more generic (without mentioning constants).

dyemanov · 2026-04-12T07:24:07Z

src/jrd/Package.epp

+	}
+
+
+	{ // Execute constant expr


Please remove the scope as well as the redundant blank line.

dyemanov · 2026-04-12T07:25:07Z

src/jrd/Package.epp

+			LiteralNode::genConstant(dsqlScratch, &descForDouble, false, len);
+			break;
+		}
+		case dtype_dec64: // dtype_dec64 is not present in LiteralNode::genConstant


Agreed, please add blank lines before case

dyemanov · 2026-04-12T07:26:38Z

src/jrd/Package.epp

+	// Gen blr into dsqlScratch
+	Firebird::AutoMemoryPool tempPool(MemoryPool::createPool(ALLOC_ARGS0));
+	CastNode cast(*tempPool, constExpr, type);
+	{


This is not the practice used in our code. Separation for readability is supported by blank lines and comments.

Artyom Abakumov added 22 commits February 11, 2026 13:28

Implement package constants

5aa9116

Add "is constant" flag to nodes

251615c

Fix blr parsing, generate unique names for constant FIELD_NAME, fix w…

2d35ecc

…rong impure cache usage

Improve error message for non constant expression

75db5ab

Add missing SCHEMA set to package constants, fix incorrect cached con…

e54c9e6

…stant routine

Add missing resource allocation and transfer for constants

45d62b7

Fix invalid constant and package name in store_dependencies

06411d7

Fix invalid constant drop

3dc1d3d

Fix constant evaluating in BLR Parse

d048560

Fix constants collecting and dtype_dec64 parsing

6231dbc

Fix incorrect ambiguity check

05342aa

Update support for complex dtypes

459354f

Cleanup

3c2c61e

Rollback unneccecery changes

fd208d1

Move all constant related routines to Constant class

8a982ac

Add description for package constants

c42bd55

Cleanup

4a556aa

Delete string in impure

44a7050

Merge remote-tracking branch 'upstream/master' into metacache_package…

c2caa1b

…_constants

Merge remote-tracking branch 'origin/master' into metacache_package_c…

4294bc4

…onstants

Resolve incorrect merge with LTT

3148971

One more cleanup (preparation) before PR

51fc8d7

dyemanov assigned dyemanov and unassigned dyemanov Feb 25, 2026

dyemanov self-requested a review February 25, 2026 08:09

dyemanov assigned Noremos Feb 25, 2026

dyemanov added type: new feature component: engine labels Feb 25, 2026

Artyom Abakumov added 6 commits April 2, 2026 12:41

Add USAGE privilege requirement to use package constant

082d5e7

Merge remote-tracking branch 'origin/master' into metacache_package_c…

d273bc0

…onstants

Add descriptions for constants added in RDB$BLOB_UTIL

fff58ef

Correct nullable flag for new fields

0284ee1

Revert blank change

84d0d0a

Adjust comments for meta objects

b85ee52

Artyom Abakumov added 2 commits April 2, 2026 18:18

Minor corrections

37c4438

Do not backup system constants

d3a0b9d

Noremos commented Apr 2, 2026

View reviewed changes

Artyom Abakumov added 8 commits April 3, 2026 10:30

Use qualifyNewName to search for SCHEMAs of constant

7b3ef78

Store constant BLR using storeBinaryBlob

93caf2e

Reorder methods in package class to match definition order

5a4b657

Fix adding existing constant to cache again on alter

bafdb37

Fix bug where cached::package lock was not released after Restore

e9445e3

Populate cache for package at after insert trigger only during restore

a1488be

Mark package field as nullable in RDB$CONSTANTS table in case of glob…

9edf966

…al constants

Final cleanup: Correct comments, remove PACKAGE_NAME.NULL checks, add…

10140bb

… grant/revoke for constants in README

Noremos commented Apr 3, 2026

View reviewed changes

Artyom Abakumov added 7 commits April 3, 2026 18:32

Minor corrections

dba49c1

Fix missing error when showing non existing constant(s)

1dcc3df

Add missing gpre call for Package.epp on windows and update vcxproj.f…

4ddaad4

…ilters

Add missing gpre call for Package.epp at boot state

8149e09

Fix resolving package and schema for constant name in SHOW command

a195eb7

Merge remote-tracking branch 'origin/master' into metacache_package_c…

f664a74

…onstants

One more cleanup

f3d7c52

dyemanov reviewed Apr 12, 2026

View reviewed changes


		bool isPrivate = !CONST.RDB$PRIVATE_FLAG.NULL && CONST.RDB$PRIVATE_FLAG;

		if (!CONST.RDB$PACKAGE_NAME.NULL)

	To use package constants in a select expression, a USAGE permission is requeued:
	To use package constants in a select expression, a USAGE permission is required:

	Header constants can also be used directly with just the name for package body elements.
	Header constants can also be referenced directly by their name inside package body elements.

Uh oh!

Conversation

Noremos commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!